This chapter describes the theory and operation of MacsBug, the Macintosh MC68xxx debugger. It also describes the syntax of commands accepted by MacsBug.
MacsBug is a line-oriented, single-Macintosh debugger. It resides in RAM along with the program being debugged. The capabilities of MacsBug include
n displaying and setting memory and registers
n disassembling memory
n stepping and tracing through both RAM and ROM
n monitoring system traps
n displaying and checking the system and application heaps
MacsBug obtains control when certain MC68000 exceptions occur. You can then examine memory, trace through the program, or set up break conditions and execute the program until those conditions occur.
MacsBug works with the following hardware configurations:
n 512K to 4 M of RAM
n 64K or 128K (Macintosh Plus) ROMs or 256K ROMs (SE and II)
n Motorola 68000 or 68020 processors
n Motorola 68881 floating-point coprocessor
v Note: MacsBug does not work on the Macintosh XL. Macintosh XL users should use MacsBug.XL, which is also provided.
MacsBug is not a normal Macintosh application. Instead, MacsBug installs itself once at boot time and remains active until shutdown. Installation occurs if the following conditions are met:
1. MacsBug exists and is named “MacsBug”.
2. It is on a startup (bootable) disk.
3. It is in the current System Folder. The System Folder is, by definition, the folder that contains a system file named System and a system file named Finder.
MacsBug is shipped in the Debuggers folder; you must move it to the System Folder to install it.
After a successful installation, the message “MacsBug installed” is displayed below the “Welcome to Macintosh” message. The startup application (normally the Finder) is then launched as usual.
Once MacsBug is installed, the only way to remove it is to reboot. To prevent the installation of MacsBug during a boot, hold the mouse button down while booting. To permanently override the installation of MacsBug, simply rename it or remove it from the disk.
v Using HFS with the 64K ROM: If you have MacsBug on an HD-20 (HFS) Startup disk on a machine with the original 64K ROM, there is a seeming conflict with the above mouse-down command, because holding the mouse button down at boot also forces the Macintosh to boot from the floppy disk rather than switch-launching to the HD-20. However, a skillful mouser can accomplish either command simply by knowing that MacsBug is installed first, right after the “Welcome to Macintosh” hello message, and that the HFS code looks for a mouse-down only after the “MacsBug installed” message.
This section provides background information about how MacsBug works. This information is important if you are interested in implementing your own Macintosh debugger; most other readers can skip this section.
The state of the world when MacsBug is about to be loaded is fairly complete. The interrupt system, Memory Manager, and ROM-based I/O drivers have already been initialized by the ROM boot code. The boot code initializes the Event Manager, the Font Manager, the Resource Manager, and the file system. (Although the Toolbox is initialized at this point, MacsBug does not use the Toolbox.) The 'DSAT' table is loaded in and the string “Welcome to Macintosh” contained therein, is displayed.
Next, the loading process of MacsBug takes place as follows: First the boot-blocks code reserves some space (1024 bytes) for MacsBug’s own global variables. Then this code looks for the file specified in the boot blocks, as described above. If the file is not found, then the global space is deallocated and the boot process continues normally without installing a debugger.
If MacsBug is found, the data fork (not the resource fork!) of the file is loaded onto the current stack, which is located immediately below the main screen buffer in memory.
v Historical note: For reasons relating to the original Lisa Workshop, the first block (512 bytes) of the MacsBug data fork is stripped off during this loading process.
The boot code then JSRs to MacsBug itself. MacsBug begins its installation process by checking to see if the mouse button is down. If it is, MacsBug aborts the installation and lets the boot process continue without installing itself. If the button is not down, MacsBug determines which kind of machine and microprocessor it is running on, and configures itself accordingly.
At the successful completion of the installation, the message “MacsBug installed” is posted below the “Welcome to Macintosh” message. The boot process then continues by loading 'INIT' resources from the System file.
v Technical note: The boot code looks for 'INIT' resources 0-31 and JSRs to them. These 'INIT' resources are used to set up the keyboard maps ('INIT's 0 and 1), install patches (of type 'PTCH') to ROM code, and so on. 'INIT' 31 extends the system further by looking for any files of type INIT in the System Folder. This facility allows you to install your own startup code without changing the System file.
Finally, the startup application is launched. The startup application is typically the Finder, but can be set to any other application via the Finder’s “Set Startup” menu item.
During installation, MacsBug obtains further memory from below the main screen buffer for use as its own screen memory. (MacsBug obtains memory from the same general area in RAM as do RAM disks and caching utilities, based on the location of BufPtr, a Macintosh global variable.) MacsBug offers a full screen display with 40 lines saved. This display uses about 22 K of memory on a Macintosh Plus or Macintosh SE. The display on a Macintosh II requires about 62 K.
The total RAM requirement of MacsBug is approximately as follows:
Macintosh Plus & SE Macintosh II
Global space 1 K Global space 1 K Screen space 22 K Screen space 62 K Code space 27 K Code space 27 K TOTAL 50 K TOTAL 90 K
MacsBug may not work with some memory-intensive applications on a Macintosh 512K. For example, using MacsBug and the MPW Pascal Compiler on a Macintosh 512K severely limits the size of programs that may be compiled. Two solutions are possible:
1. Remove MacsBug to free up about 50K of RAM.
2. Add additional RAM via the Macintosh Plus Logic Board Upgrade or a compatible third-party hardware upgrade to 1 megabyte or more of RAM.
When installed, MacsBug puts pointers to itself in many of the hardware exception vectors in addresses $0000 0000 through $0000 00FF. It then remains dormant until one of “its” exceptions occurs. The following is the list of exceptions to which MacsBug responds; each is numbered one greater than the corresponding Macintosh System Error number.
Exception # Assignment
2 Bus error (rarely seen on the Macintosh) 3 Address error (not aligned to a word boundary) 4 Illegal instruction (bit pattern not recognized) 5 Zero divide 6 CHK instruction (array index out of bounds) 7 TRAPV instruction (overflow) 9 Trace (used to single-step in MacsBug) 10 Line 1010 emulator (the A-trap handler for all Toolbox traps) 11 Line 1111 emulator (68xxx coprocessor trap interface) 28 Level 4 interrupts 29 Level 5 interrupts 30 Level 6 interrupts 31 Level 7 interrupts 47 Trap $F instruction (used for setting programmer breaks)
MC68000 exception processing is described in the Motorola 68000 Programmer’s Reference Manual.
Any time an A-trap or other exception listed above occurs, MacsBug intercepts the trap and can thus stop or display the current state of the machine. Single-stepping through 68xxx instructions is possible because MacsBug can set the Trace bit in the status register of the microprocessor. MacsBug saves the ROM-based A-trap handler address in the long word immediately preceding its own A-trap handler routine. Thus, if you need to access the real ROM A-trap handler when MacsBug is installed, you can look at the long word before the address of the current handler.
The simplest way to get into MacsBug is to generate an exception by pressing the interrupt button. (The interrupt button is the rear button of the programmer’s switch on the Macintosh, or the minus key on the numeric keypad on the Macintosh XL.)
To see the application screen while the debugger is active, press the tilde/back quote key (~/ `) in the upper-left corner of the keyboard. To restore the debugger’s display, press any character key. Repeated presses toggle between the two screens, allowing easy viewing of both the actual code (MacsBug screen) and the results (main screen).
The best way to enter the debugger programmatically is to set a breakpoint in your program by using the system trap called Debugger at the point where you want MacsBug to get control. There are two ways to use this trap. Calling trap $A9FF drops into MacsBug and displays the message “USERBRK”. It then does a normal exception entry into MacsBug (unless you have toggled the DX command—see “Break Commands” later in this chapter).
If you want to display custom debugging information, declare and call the trap with bit 10 set ($ABFF). When this latter trap is encountered, MacsBug assumes that the top of the user’s stack has a pointer to a Pascal string. It prints out the string, displays the message “USERBRK,” and does a normal exception entry into MacsBug. As $ABFF is a procedure call, MacsBug takes care of popping the string pointer off the stack.
Here is a summary of how to declare and use this trap on a per language basis.
Assembly language
Declaration
_Debugger OPWORD $A9FF ; predefined in the file ToolTraps.a _DebugStr OPWORD $ABFF ; not predefined - define yourself
Example calls
(a) _Debugger ; enters MacsBug and displays USERBRK (b) STRING PASCAL ; Asm directive to make sure to push a ; Pascal string PEA #'Entered main loop' ; push address of string on stack _DebugStr ; enters MacsBug and displays message
(a) Debugger(); /*enters MacsBug and displays USERBRK*/ (b) DebugStr(c2pstr("Entered main loop")); /*enters MacsBug, displays message*/
When MacsBug gets control, it disassembles the instruction indicated by the program counter and displays the contents of the registers. If the exception was caused by a $A9FF or $ABFF instruction, MacsBug displays the message “USERBRK”, advances the PC to the next instruction, and then disassembles the instruction and displays the registers. It then displays the greater-than symbol (>) as a prompt, indicating that it is ready to accept a command.
v Note: There are two other ways to enter MacsBug: by using 'FKEY' and 'INIT' resources. With ResEdit, a skilled user can create a custom resource of either type whose sole function is described by two simple MC68000 instructions: $A9FF $4E75 ( _Debugger and RTS; that is, the sequence to enter MacsBug).
Another way to generate an exception that was popular in the past was to add a line such as
DC.W $FECE ; generate a line 1111 exception
at the point in your program where you wanted MacsBug to get control. (Any value $F000 through $FFFF could have been used.) This method should not be used any more, as these instructions have been reserved by Motorola for use in their coprocessor interface for the 68020 microprocessor. (For example, in the future these “exceptions” could actually be MC68881 floating-point instructions!)
Commands consist of a one- or two-character command name followed by a list of zero or more parameters (depending on the command). A return character repeats the last command entered, unless otherwise specified in the command description.
Parameters can be numbers, text literals, symbols, or simple expressions. All parameters can be entered as expressions. Parameters are represented by descriptive words and abbreviations such as address, number, and expr.
MacsBug commands can be divided into five groups: memory, break, A-trap, heap zone, and disassembly commands.
As is fitting for a debugger, all numbers are hex unless otherwise specified. Decimal numbers are preceded by a number sign (#). Hexadecimal numbers can optionally be preceded by a dollar sign ($). Numbers can be signed (+ or –). A hex word (four hex characters) preceeded by a less-than symbol (<) is sign-extended to a long word.
Here are some numbers in different formats—the formats shown are the same as those displayed by the CV (Convert) command, described later in this chapter.
A text literal is a one- to four-character ASCII string bracketed by single quotes ( ' ). If a string is longer than four characters, only the first four characters are used. When used by MacsBug, text literals are right justified in a long word. Here are some examples:
The following symbols are generally used to represent the MC68xxx registers:
RA0, RA1,…RA7 The contents of address registers A0 through A7 RD0, RD1,…RD7 The contents of data registers D0 through D7 PC The contents of the program counter SR The contents of the status register
v Note: In any expression where you want to use the value of one of the main registers, use the Rxx form, as shown above. If you specify A0 for example, it will be interpreted as address A0, a valid hex address, not as register A0.
In addition, the following symbols are used for frequently referenced locations:
. A period (“dot”) gives the last address referenced TP “thePort”—the address of the current QuickDraw port
Expressions are formed by operators acting on numbers, text literals, and symbols. The operators are
+ Addition (infix); assertion (prefix)
– Subtraction (infix); negation (prefix)
@ or * Indirection operator (two different prefix operators with identical functionality)
Note: The indirection operator uses the long integer at the location pointed to by the operand.
& Address operator (prefix)
< Add sign-extended number (infix); sign extension (prefix)
Expressions are evaluated from left to right. All operators are of equal precedence. There is no way to alter the order of evaluation. Here are some valid expressions:
(Help): Displays a short list of MacsBug commands and their parameters.
DV
(Display Version): Displays the version, the date and time of creation, and the signature of MacsBug. For example,
MACSBUG 5.1B1 17-May-86 00:05:10 <DKA>
RB
(Reboot): Reboots the system.
ES
(Exit to Shell): Invokes the trap ExitToShell, which causes the current shell to be launched. (The “current shell” is usually the Finder, but you can change it by editing the Finder field of the boot blocks.) The current shell must reside in the System Folder and is logically distinct from the startup application.
v Technical note: ES may not work with applications that override important system traps. This problem occurs because the application heap gets initialized promptly upon calling the trap ExitToShell; the initialization usually trashes any system patches that were located there. However, there is a hook called IAZNotify, called by InitApplZone, that you can use to restore the world before purging the otherwise necessary routines.
EA
(Exit to Application): Relaunches the application. This is a faster method than calling ES and relaunching from the Finder.
(Convert): Displays expr as unsigned hexadecimal, signed hexadecimal, signed decimal, text, and binary.
DM [ address [ number ] ]
(Display Memory): Displays number bytes of memory starting at address.
Number is rounded up to the nearest 16 bytes. If number is omitted, 16 bytes are displayed. If address and number are both omitted, the next 16 bytes are displayed. The dot symbol ( . ) is set to the address of the beginning of the last block displayed.
If number is set to certain four-character strings, memory is symbolically displayed as a data structure that begins at address. The strings and the data structures they represent are
'IOPB' Input/Output parameter block for file I/O 'WIND' Window record 'TERC' TextEdit record
(Refer to Inside Macintosh for a description of these data structures.)
You can usually terminate a DM command by pressing the Backspace key.
SM address expr…
(Set Memory): Places the specified values, expr…, into memory starting at address. The size of each value depends on the “width” of each expression. The width of a decimal or hexadecimal value is the smallest number of bytes that holds the specified value (four-byte maximum). Text literals are from one to four bytes long; extra characters are ignored. Indirect values are always four bytes long. The width of an expression is equal to the width of the widest of its operands. The dot symbol ( . ) is set to address.
DB [ address ]
(Display Byte): Displays a single byte of memory located at address. This command automatically calls the convert routine as well, allowing you to see flags easily. DB is useful for looking at the contents of memory-mapped IO registers. (Using DM will read larger portions of memory; this can have undesired side effects on the peripheral chips being examined.)
SB address [ expr ]
(Set Byte): Places the value of expr into the byte located at address. If no expr is given, then it clears the byte to zero. Like DB, this command is useful for debugging memory-mapped I/O registers.
Dn [ expr ]
(Data Register): Displays or sets data register n. If expr is omitted, the register is displayed. Otherwise, the register is set to expr.
An [ expr ]
(Address Register): Displays or sets address register n. If expr is omitted, the register is displayed. Otherwise, the register is set to expr.
PC [ expr ]
(Program Counter): Displays or sets the program counter. If expr is omitted, the program counter is displayed. Otherwise, the PC is set to expr.
SR [ expr ]
(Status Register): Displays or sets the status register. If expr is omitted, the status register is displayed. Otherwise the status register is set to expr.
TD
(Total Display): Displays all of the MC68000 registers and the PC, and disassembles the current instruction that is about to be executed upon stepping, tracing, or going.
TF
(Total Floating Point): Displays all of the MC68881 registers if the floating-point chip is present. TF displays register values in both decimal and scientific notation.
Fn [ expr ]
(Floating Data Register): Displays or sets the specified MC68881 floating-point data register n. You can directly set the register to a decimal or scientific notation value. If expr is omitted, the register is displayed. Otherwise, the register is set to expr.
FI [ expr ]
(Floating Instruction Address Register): Displays or sets the MC68881 floating-point instruction address register. If expr is omitted, the register is displayed. Otherwise the register is set to expr.
FC [ expr ]
(Floating Control Register): Displays or sets the MC68881 floating-point control register. If expr is omitted, the register is displayed. Otherwise the register is set to expr.
FS[ expr ]
(Floating Status Register): Displays or sets the MC68881 floating-point status register. If expr is omitted, the register is displayed. Otherwise the register is set to expr.
CS [ address1 [ address2 ] ]
(Checksum): Checksums the bytes in the range address1 through address2 and saves that value. The checksum is an exclusive OR of the bytes in the range specified. If address2 is omitted, CS checksums 16 bytes, starting at address1. If address1 and address2 are both omitted, it calculates the checksum for the last range specified, saves that value, and compares it to the previous checksum for that range. If the checksum hasn’t changed, CS prints CHKSUM T; otherwise it prints CHKSUM F.
v Note: For checksumming memory in conjunction with A-traps, see the AS command. For checksumming after every 68xxx instruction, see the SS command.
(Break): Sets a breakpoint at address. Count specifies the number of times that the breakpoint should be executed before stopping the program. If count is omitted, the program is stopped the first time the breakpoint is hit. If address is omitted, all breakpoints are displayed. You can set a maximum of eight different breakpoints.
CL [ address ]
(Clear): Clears the breakpoint at address. If address is omitted, all breakpoints are cleared.
G [ address ]
(Go): Executes instructions starting at address. If address is omitted, execution begins at the address indicated by the program counter. Control does not return to MacsBug until an exception occurs.
GT address
(Go Till): Sets a one-time breakpoint at address, then executes instructions starting at the address indicated by the program counter. This breakpoint is automatically cleared after it is hit.
T
(Trace): Traces through one instruction. Traps are treated as single instructions.
If the next instruction to be executed is a JSR to a currently unloaded segment, you will see the LoadSeg ($A9F0) trap instead of the JSR. Tracing through that instruction will not work normally. If you wish to trace through the LoadSeg trap, you need to set a low-memory global at location $12D to a nonzero value. Do a SB 12D 1 to enable tracing through the LoadSeg call. Next, Go (G). You will break at an RTS instruction. Trace once (T) to see the absolute location that you are about to jump to. Trace again and you will be at the first step of the routine that is now loaded into memory. To turn off tracing through LoadSeg calls, simply execute SB 12D to clear the LoadSeg low-memory flag.
S [ number ]
(Step): Steps through number instructions. If number is omitted, just one instruction is executed. Traps are not considered to be single instructions. Step will display each instruction as it is executed.
SS address1 [ address2 ]
(Step Spy): Calculates a checksum for the specified memory range, then does a Go; it then checks the checksum before each 68xxx instruction is executed, and breaks into MacsBug if the checksum does not match. If address2 is omitted, SS checksums the long word at address1. This feature is turned off by entering MacsBug via the programmer’s switch or by SS terminating when the checksum has changed.
Step Spy is very slow. Step Spy is nevertheless useful for detecting what routines are stepping on a specific place in memory. If checking memory at every A-trap is sufficient for your needs, use the AS command, described below. (The slow motion capability of SS, however, can be useful in its own right to examine how the Finder zooms windows, for example. Think of it as a tool to study graphics algorithms.)
ST address
(Step Till): Steps through instructions until address is encountered. Unlike Go Till, this command does not set a breakpoint. Thus it can be used to step through, and stop in, ROM.
MR [offset ]
(Magic Return): This command lets you quickly step through an entire procedure. It does this by replacing the return address on the stack with an address in MacsBug. When the procedure returns, control first goes to MacsBug. MacsBug restores the original return address and then executes an RTS in trace mode. MacsBug breaks at the instruction after the call to this procedure.
If offset is omitted, then MacsBug assumes the return address is on the top of the stack. If offset is present, then it is interpreted relative either to the stack pointer (A7) or the frame pointer (A6). If offset is less than A6, then MacsBug assumes that the return address is at A7 + offset. If offset is equal to A6, thenMacsBug assumes that A6 is the frame pointer placed on the stack by the LINK instruction as a procedure preamble. If offset is greater than A6, then it is assumed to be the frame pointer of a procedure located higher in the calling order.
Examples:
MR
Use MR if the called procedure has not changed the stack
MR n
Use this command if the called procedure has pushed n bytes onto the stack.
MR RA6
Use this command if the called procedure has done a LINK instruction.
MR @RA6
Use this command to break after the caller of the called procedure returns.
DX
(Debugger Exchange): Normally, if either the $A9FF or the $ABFF A-trap (two forms of the Debugger trap) is executed, program execution halts and the debugger is activated. DX allows you to control whether or not program execution halts. Note that the $ABFF trap will still print a string; thus with debugger entry disabled, an effect similar to that of the AT command occurs—that is, the Macintosh screen alternates between the debugger and the program. The default is to stop at Debugger traps.
The A-Trap commands are used to monitor “1010 emulator” traps, used to call the Macintosh ROM. These commands take up to six parameters (trap1, trap2, address1, address2, D1, and D2). These parameters indicate which traps and other conditions should be monitored:
n Trap1 and trap2 specify the range of the traps. If only trap1 is specified, the command is invoked for trap1. If trap1 and trap2 are specified, the command is invoked for all traps in the range trap1 through trap2. The defaults are $A000 and $AA00.
$A000–$A0FF Operating system traps
$A800–$A9FF Toolbox traps
0–$6F Shortcut expressions for OS traps
$70 and greater Interpreted as Toolbox traps
n Address1 and address2 specify a range of memory addresses within which traps should be monitored. The defaults are 0 and $FFFFFFFF.
n D1 and D2 specify the values of data register 0 within which traps should be monitored. They are treated as unsigned numbers. The defaults are 0 and $FFFFFFFF.
Thus, if no parameters are given, all traps are monitored.
A-trap commands allow two commands to take place simultaneously. The trick to using the A-trap commands is to know that there are separate flags for tracing and breaking, and that separate globals are used for storing the general trap range (GTR) and the breaking trap range (BTR):
n Any A-trap command (AA, BA, AT, AB, AS, AH, AR) sets the tracing flag. In addition, any command except AS can supply a trap range, which is always stored in the GTR variable.
n Executing an AB or BA also sets the breaking flag. It also saves the trap range you supplied in both the GTR and BTR variables.
In the previous release of MPW, any A-trap command would clear all flags, but in MPW 2.0 only AX clears all flags. If you are a “casual” A-trap user, execute AX before executing any A-trap commands in order to avoid undesired breaks. However, for the MacsBug power user, combined A-trap commands can be very useful.
Here is an example of how you can use combined A-trap commands. If you wish to view (trace) all of the file system traps called from your application but also want to break at the next Open call that you make, you would type (and in this order!):
>BA Open >AA 0 17 (shorthand for file system traps)
The AA command is entered second so that its range overwrites the GTR supplied by the BA command. This way you can view (trace) the “wider” range of traps while breaking on the “smaller.”
(Break in Application): Causes a break when the conditions specified by the parameters are satisfied and the trap is being called from the application rather than from the ROM. Address1 and address2 are automatically set to ApplZone and BufPtr. Therefore you can use this command to get back to the application when in ROM. Simply type BA, (return),and then, G, (return). MacsBug will be entered at the next trap called by code located in the application heap. To break on ROM calls as well (or traps called from the system heap or elsewhere), use AB, described below.
(Application A-trap Trace): Traces and displays each A-trap called from the application heap without breaking if the conditions specified by the parameters are satisfied. AA continues to display A-traps until you press the interrupt button. AA allows you to monitor only the traps that the application calls, and thus can be useful for checking and measuring performance. To monitor all traps called, including calls made from inside the ROM and traps called from the system heap, use the AT command.
(A-trap Break): Causes a break when the conditions specified by the parameters are satisfied. AB without any parameters will stop at the very next trap executed anywhere by the Macintosh. To stop at the next trap called by the current application, use BA instead.
(A-trap Trace): Traces and displays each A-trap without breaking, when the condition specified by the parameters is satisfied. AT continues to display all A-traps until you press the interrupt button. If you wish to see just the traps called by the current application, use AA instead.
For example, to see all QuickDraw calls displayed, regardless of who calls them, you could type
(A-trap Heap Zone Check): Checks the heap zone for consistency just before executing each trap in the specified range. If an inconsistency is found, it displays the addresses of the two memory blocks in question.
(A-trap Record): Whenever the parameter constraints are satisfied by an A-trap call, information about the call is recorded. The trap name, PC, A0, D0, and the time are always saved. If the call was for an OS trap, 32 bytes pointed at by A0 are recorded; otherwise 32 bytes pointed at by A7 (the stack pointer) are saved. To display the current saved information, type AR with no arguments.
This command is especially useful for tracking down crashes in the Macintosh ROM. For example, the command
>AR 0 1000 @2AA @114
records traps 0 through 1000 (all traps), from ApplZone ($2AA) through HeapEnd ($114), so it will record the last trap call made from anywhere in the application heap (the application’s code).
AS address1 [ address2 ]
(A-trap Spy): Calculates a checksum for the specified memory range, checks it before each A-trap that is called, and breaks into MacsBug if the checksum does not match. If address2 is not specified, AS checksums the long word at the given address. Use SS if you want the range of memory to be checked before every 68xxx instruction rather than before every A-trap only. AS is turned off by AX.
AX
(A-trap Clear): Clears all A-trap commands and turns off Heap Scrambling.
The heap zone commands act upon the current heap zone. When MacsBug is started up, the current heap zone is the application heap zone. You can set the current heap zone by using the HX command. Several commands cause MacsBug to scramble the heap zone. When you scramble the heap zone, all the relocatable blocks are rearranged (see HS below). Scrambling is useful for finding illegally used pointers to relocatable data structures.
HX [ address ]
(Heap Exchange): Sets the current heap to address. If no address is given, then HX toggles the current heap zone between the system heap zone and the application heap zone. In any case, HX displays the resulting current heap address.
HC
(Heap Check): Checks the consistency of the current heap zone, and displays the addresses of inconsistent memory blocks as well as the address of the current heap.
HS
(Heap Scramble): Scrambles the heap zone by calling CompactMem each time a Memory Manager trap is called. Heap Scramble is useful for finding nil handles, dangling pointers, and other mistakes made in memory management. It also performs a heap check after each scramble. If the heap looks questionable, MacsBug will inform the user. Use AX to turn Heap Scramble off.
HD [ mask ]
(Heap Dump): Mask is optional. Whether or not mask is used, it displays each block in the current heap zone in the following form:
blockAddr type size [ flag MP_location ] [ * ] [ refNum restype ID ]
n blockAddr points to the start of the memory block.
n type is one of the following letters:
F Free block
P Pointer
H Handle to a relocatable block
n size is the physical size of the block, including the contents, the header, and any unused bytes at the end of the block.
n For handles (type H), flag is either blank if not purgeable or a P if purgeable. Then MP_location is displayed, which is the address of the master pointer to the relocatable block.
n The asterisk (*) marks any locked object (nonrelocatable blocks and locked relocatable blocks).
n For resource file blocks, three additional fields are displayed: the resource’s reference number, resource type, and ID number. If mask is omitted, then the dump is followed by a summary of the heap blocks. If mask is present, then only certain types of heap blocks are displayed. Mask should be one of the following text strings:
'h' Relocatable blocks (handles) 'p' Nonrelocatable blocks (pointers) 'f' Free blocks 'r' All resource blocks 'XXXX' Only resource blocks of the type 'XXXX'
If mask is used, the heap summary takes this form:
CNT ### <# of blocks of mask type> <# bytes in those blocks>
You can prematurely terminate an HD command by pressing the Backspace key.
The dot address ( . ) is set to the last block of memory displayed by HD.
HT [ mask ]
(Heap Total): Displays just the summary line from a heap zone dump. Mask works just as it does with the HD command (described above).
SC
(Stack Crawl): Assumes that LINK / UNLK A6 has been religiously performed at the beginning and end of each procedure or function. (The $D+ directive in Pascal, and the -g and -ga options in C force these instructions to be performed.) The output format is as follows:
SF @<stack frame location> <address of call to procedure>
For example,
SF @0D633C ProcName+3A
means that the currently executing procedure or function has its local stack frame at $D633C and was called from ProcName+$3A (which is not the return address!). If the program counter is in the ROM, SC may not work properly.
(Symbol Exchange): Determines whether or not symbols are displayed. By default, symbols are turned on. SX affects any command that takes an address. Using symbols allows you to disassemble an intruction list (IL) or break (BR) on a procedure or function name. For example,
>IL ProcName+58
disassembles code starting at 58 bytes (hex) into the procedure called ProcName, and
>BR ProcName+58
sets a breakpoint at the same location. (This also works for GT, ST, DM, and so on.)
When searching for symbols, MacsBug searches the current heap (set by the HX command). The heap is searched by walking through memory and looking for locked blocks of memory. Then, within locked blocks, MacsBug first looks for a LINK A6 instruction followed by a matching UNLK A6 instruction. Then MacsBug looks for either an RTS or a JMP (A0) instruction.
Immediately following one of these last two instructions should be an 8-character symbol. This symbol must be exactly eight characters long; it should be padded with blanks if it is less than eight characters. Some compilers set the high bit on the first character of the symbol, but MacsBug clears this bit. In addition, if the high bit of the second character is set, MacsBug expects a 16-character name (used mainly for method names in MacApp-generated code.) To see all of the symbols that are valid at any given moment, use the SD command (described next).
Turning symbols off is helpful for two reasons. First, every symbol lookup traverses the current heap, and therefore may degrade the speed of the disassembly. Secondly, if you prefer always seeing a dump of code in hex rather than symbols (useful when looking at ROM code, for example), turning off symbols will guarantee a hex dump of your code. This hex dump displays the main opcode word followed by two extension words which may or may not apply to the particular instruction disassembled.
SD [ address ]
(Symbol Dump): Displays a list of the procedure names that can be found in the current heap zone. The search criteria are based on looking in each block of memory whose locked bit is set. In addition, a LINK A6 and its matching UNLK A6 must be found, followed by either a JMP (A0) or an RTS. The 8-character debugging name follows. Valid debug symbols must consist of ASCII characters in the range $20–$5F (space–underscore), inclusive. This command optionally allows you to specify a starting location for the symbol dump.
DH number
(Disassemble Hex): Disassembles the hex byte, word, or long word input. Typing just one byte allows you to see the general class of instructions, as number is left-aligned in a long word padded to the right with zeros. (Typing DH 10, DH 20, and DH 30, for example, shows by induction that these instruction groups are the Move.B, Move.W, and Move.L classes, respectively.)
This command is useful as a poor man’s assembler. For example, if you wanted to use the RESET instruction and could not remember what its opcode was, you could type DH 4E71 as a first guess and DH would display NOP. Trying DH 4E70 as a second guess would reveal the actual RESET instruction.
ID [ address ]
(Instruction Disassemble): Disassembles one line at address. If address is omitted, the next logical location is disassembled. ID sets the dot symbol ( . ) to the address.
If the code has symbols compiled with it via the $D+ directive in Pascal or the -g option in C, and symbols have been turned on with the SX command, each address is automatically displayed as a routine name plus an offset.
IL [ address [ number ] ]
(Instruction List): Disassembles number lines starting at address. If number is omitted, a screenful of lines (typically 16) is disassembled. If both number and address are omitted, a screenful of lines is disassembled starting at the next logical location. This command sets the dot symbol ( . ) to the address.
If the code has symbols compiled with it via the $D+ option in Pascal or the -g option in C, and symbols have been turned on with the SX command, each address is automatically displayed as a routine name plus an offset.
You can prematurely terminate an IL command by pressing the Backspace key.
F address count data [ mask ]
(Find): Searches count bytes from address, looking for data, after ANDing the target with mask. As soon as a match is found, the address and value are displayed, and the dot symbol ( . ) is set to that address. To search the next count bytes, simply press Return. The size of the target is determined by the width of data; it is limited to 1, 2, or 4 bytes.
For example, to find a RESET instruction in a program loaded into a Macintosh Plus, you could type
>F CB00 EFFFF 4E70
where CB00 is the beginning of the application heap, EFFFF represents the length of the application heap (roughly), and 4E70 is the RESET instruction.
WH expr
(Where): Takes an expression, which can be a symbolic name, and displays the location of the first routine that it finds whose name matches the expression. ROM symbol names are 10-character names, and RAM symbols are 8-character names.
If expr is less than $AA00, this command displays the address corresponding to the trap with that number. All of the following commented commands, for example, give the same result:
>WH EXITTOSHELL ; full name >WH A9F4 ; full trap word >WH 1F4 ; shortcut >WH 40F6D8 ; address of ExitToShell in the 128K ROM
Namely,
Trap word Address Name
A9F4 40F6D8 EXITTOSHELL
The shortcut method of inputting trap numbers interprets $0–$6F as OS traps, and all other traps as Toolbox traps.
If expr is preceded by the address operator (&), then the expression is forced to be evaluated as an address. This feature is useful for examining system patches whose addresses are often less than $AA00, the default address boundary.
If expr is greater than or equal to $AA00 and less than RomBase, then the address is interpreted as a user routine in RAM, and a symbolic location and code segment will be displayed if possible.
If expr is in ROM then the trap whose code is closest to that address is displayed.
WH is useful for finding out where you were when an error occurred. If the address expression is in RAM and the WH function returns “PRGM AT $$$$” you can use the command HD 'CODE' to list the code segments. Then, by comparing the locations of 'CODE' segments and the current PC, you can determine which segment you are in.
